Repository navigation
Python codegen: docstrings and attribute-access ENV for hover docs - #1219
Merged
Merged
Conversation
@generatePythonEnv now emits an EnvAttrs class with a documented property per item and a lazily loaded module-level ENV, so Pyright/Pylance show item docs on hover where values are read. Env TypedDict fields get attribute docstrings instead of # comments, deprecated items map to typing_extensions.deprecated, and NotRequired comes from typing_extensions so checkers targeting < 3.11 work. Closes #1215
Contributor
|
The changes in this PR will be included in the next version bump.
|
Contributor
📦 Bundle size
dist/ only; native binaries are versioned separately and not counted here. |
varlock
@varlock/native-helper-darwin
@varlock/native-helper-linux-arm64
@varlock/native-helper-linux-x64
@varlock/native-helper-win32-x64
commit: |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Important
Valid env keys can make the new attribute-access module fail mypy checking because properties shadow type names used in later annotations.
Reviewed changes Reviewed the Python generator, shared documentation sanitization, tests, and user documentation.
- Attribute access: Adds documented
EnvAttrsproperties and a lazily loaded, cached module-levelENV, while retainingload_env()dict access. - Editor documentation: Emits escaped field and property docstrings, Markdown documentation links, sensitivity information, and type-checker deprecation markers.
- Compatibility and coverage: Moves
NotRequiredto type-onlytyping_extensionsimports, filters reserved property names, and updates tests and Python usage guides.
gpt-6.1-sol ｜ 𝕏
A property named after a type the class body references (str, int, Env, ...) shadows it for later annotations, which mypy rejects.
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes Reviewed the reserved-name fix since the prior review at 2124f16f.
- Expanded collision filtering: Omitted type-name keys from
EnvAttrswhile retaining them in theEnvdict, preventing mypy errors in later property annotations. - Strengthened regression coverage: Added colliding names before an optional getter; all eight emitter tests and an independent generated-module probe passed mypy strict and Python runtime checks.
- Updated documentation: Listed the additional reserved attribute names and explained the
load_env()fallback.
gpt-6.1-sol ｜ 𝕏
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
varlock-website | 8d337a7 | Commit Preview URL Branch Preview URL |
Oct 13 2026, 09:15 PM |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1215.
@generatePythonEnvoutput now shows item docs in the editor where values are read.EnvAttrsclass with one documented, typed@propertyper item, plus a lazily loaded module-levelENV(from env import ENV; ENV.DB_PORT). Loads on first access and is cached, so importing the module stays side-effect-free. The module__getattr__is hidden from type checkers so typo'd imports still error.EnvTypedDict fields get attribute docstrings instead of#comments (description,@docs()as Markdown links, deprecation, valid values, sensitivity). Quotes and backslashes are escaped.@deprecateditems gettyping_extensions.deprecatedon the property (type-checker-only import, runtime no-op), so checkers flag reads and editors strike them through.NotRequirednow comes fromtyping_extensions, fixing pyright errors on the generated file when targeting Python < 3.11.load_env()and theEnvdict are unchanged.Verified with the pyright language server (hover + go-to-definition on
ENV.KEY), pyright strict and mypy strict on 3.8/3.9 and 3.13, and a runtime import on Python 3.9.Not included: the issue's proposed
Source:line (the TS output doesn't have it either; it needs item source paths plumbed into the generators).